Getting Started with AsciiDoc Using Antora

A popular Static Site Generator (SSG) that supports the use of AsciiDoc syntax is Antora. Static Site Generators are tools that generate a full static HTML website based on raw data and a set of templates and Antora is one that has been designed specifically around the needs of technical writers and their goal; which is to create technical documentation.

Antora is developed around the AsciiDoc syntax or format that is somewhat similar to the Markdown syntax. It also runs on Asciidoctor, a processor that parses and converts AsciiDoc source documents into various formats such as HTML5, PDF, DocBook etc. It provides technical writers with a structured and defined way of organizing technical content.

It is important to note that the developers of Asciidoctor are also the maintainers of Antora, this gives room for proper integration between the two technologies.

To use Antora to generate a document, you need to assemble your files into a standard project structure, and then store them in a git repository. Once that is done, Antora picks your file and transforms it into a website.

Now you will take a look at how to Install Antora.

Installation, Setup and Configuration

Before installing Antora locally on your computer, it is important to take a look at the Supported Platforms and System Requirements. This is to ensure your development device is supported by the system.

Installing Node.js and Chocolatey for Windows

After checking for system requirements, you need to ensure you have Node.js installed on your computer. To check if you do, open the PowerShell and type:

node --version

You should see something like the image below ;

Fig 1. An Image of the PowerShell showing the node version installed

Pin 1 shows the command used to check if Node.js is installed.
Pin 2 shows the version of Node.js installed.

If you are presented with an error in your PowerShell after running the command, that would mean you do not have Node.js installed.

The best way to install to install Node.js is by Chocolatey, a package manager for Windows. Open the PowerShell and run as an Administrator by right-clicking the PowerShell icon and selecting Run as Administrator.

Then run the following command;

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.webClient).DownloadString('https://chocolatey.org/install.ps1'))

Fig 2: A screenshot of the PowerShell showing the installation of Chocolatey

Once the command is complete, you can now install node.js

You can install Node.js with Chocolatey by running the following command in the PowerShell;

choco install nodejs.install

Fig 3: A screenshot of the PowerShell showing the installation of Node.js

Installing Antora

In this section, you will look at how to install Antora.

Prerequisite: You must have Node.js installed

To be able to use Antora to generate a documentation site, you are going to need the Antora command line interface (CLI) and the Antora site generator.

The first thing to do when trying to install Antora is to create a new directory for your documentation site, and then move into that directory. You can do this in your PowerShell. Let us call this directory test-site

mkdir test-site
cd test-site

The next step is to initialize the package.json file and install the necessary CLI package in the project so you can run Antora using Node Package Execute ( npx: a npm package runner that executes any package from the npm registry without having to install it ).

node -e "fs.writeFileSync('package.json', '{}')"
npm i -D -E antora

Warning: In case you run into an error running the Antora installation script in the PowerShell of your Windows machine, refer to this article on Execution Policies to fix the issue.

Verify Antora has been installed by running the command below;

npx antora -v

If the installation is successful, the version of Antora CLI and the site generator specified will be printed onto the PowerShell.

Fig 4: A screenshot of the PowerShell that shows the various processes discussed above

From the screenshot above, you can see a visual breakdown of the Antora installation process in PowerShell. Below is an explanation of each highlighted section:

Pin 1: Creation of the test-site directory
Command used: mkdir test-site
Pin 2: Navigating into the new directory
Command used: cd test-site
Pin 3: Initializing the project with a package.json and related files
Command used: npm init
Pin 4: Installing Antora as a dependency
Command used: npm install @antora/cli @antora/site-generator-default
Pin 5: Verifying the installed version and checking that Antora is working
Command used: npx antora --version

Creating a Playbook with IDE (Visual Studio Code)

To create a documentation site, Antora needs a playbook. you will look at how to do that in this section. Follow the following steps

Step 1: Using your preferred IDE, create a new file

Step 2: Add the following configuration information to the file and save it as antora-playbook.yml:

site:
  title: Antora Docs
  start_page: component-b::index.adoc
content:
  sources:
    - url: https://gitlab.com/antora/demo/demo-component-a.git
      branches: HEAD
    - url: https://gitlab.com/antora/demo/demo-component-b.git
      branches: [v2.0, v1.0]
      start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Fig 5: A screenshot of an IDE showing the antora-playbook.yml file

This configuration file will create a site using the Antora demo repositories.

Step 3: In the terminal, navigate to the test-site directory

Step 4: Run the following command to generate your documentation site:

npx antora --fetch antora-playbook.yml

This command lets Antora clone the content, UI repository and generate your documentation site to the default output directory.

Fig 6: A screenshot from the terminal showing that the generation of documentation site is complete

Fig 6: A screenshot from the terminal showing that the generation of the documentation site is complete

Navigate to the test-site/build/site/index.html directory. Open the index.html file in your browser to view your generated documentation site.

Step 5: After opening the index.html file, you should see your generated documentation site.

Fig 7: A screenshot of the generated Antora documentation site.

Congratulations, you just created your first documentation site with Antora.

Testing your Documentation Site and Publishing with Antora

To be able to publish and test your documentation site, you should do the following:

In your already created folder, clone the content of this Github repository into it.
Once you have the repo cloned, now you can work locally on your pc.
Change into the antora directory and then initialize the json package and install antora by running the following commands;

node -e "fs.writeFileSync('package.json', '{}')"
npm i -D -E antora

Now generate your site by running the following command;

npx antora antora-playbook.yml

Now your site should be generated and ready to be viewed. Copy the displayed URL, and paste it into your browser to view your generated site.
To test for AsciiDoc syntax, navigate to the displayed folder below;
- antora/
  - docs/
    - modules/
      - module_one/
        
        pages/
        
        gettingstarted.adoc
        
        installation.adoc
        
        overview.adoc
In the gettingstarted.adoc, installation.adoc and overview.adoc files, copy and paste your AsciiDoc syntax into any of the files, then generate the site again by running the “npx antora antora-playboook.yml” command again.
Go to your browser, and refresh to see your AsciiDoc syntax displayed.

note

For any change you make with syntax in your vs code, always generate the site again by running the “npx antora antora-playbook.yml” command.

Create a GitHub repository of your own, and push changes you have made to this repo you created.
Once you have pushed to Github, configure the Github pages for your repo, and set Build and Deployment source to Github Actions.
Use the Git Action workflow below to deploy your Antora page to GitHub pages.

Be sure to have enabled Github pages in your repo by creating a gh-pages branch

Simple workflow to deploy static content to Github Pages

name: Deploy Antora static content to Pages
on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]


  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:


# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: write
  pages: write
  id-token: write


# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as you want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false


jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest


    steps:
      - name: Checkout
        uses: actions/checkout@v4


      - name: Setup Pages
        uses: actions/configure-pages@v4


      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: "./build/site"


      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/site # Update this to match your Antora output directory

Make edits to your documentation file.
Commit changes and push them to your repository.
Your content will be live once changes have been to the repository.

Installation, Setup and Configuration​

Installing Node.js and Chocolatey for Windows​

Installing Antora​

Creating a Playbook with IDE (Visual Studio Code)​

Testing your Documentation Site and Publishing with Antora​

Simple workflow to deploy static content to Github Pages​